클로드 코드 완벽 가이드 — 24장 Claude Squad 딥다이브 학습 노트

출처: 클로드 코드 완벽 가이드 (코드팩토리 최지호) | 참고: https://github.com/codefactory-co

24장에서 다루는 내용

• Claude Squad의 개념 — Git Worktree + tmux 기반의 병렬 에이전트 관리 도구
• Claude Squad 설치하기 — macOS 환경에서 Homebrew/curl을 이용한 설치
• Claude Squad 사용법 — 인스턴스 생성, 세션 진입/이탈, Diff 확인, Push까지의 전체 워크플로

전체 흐름도

[Claude Squad 개념]                    [설치]                        [사용법]
    |                                   |                              |
    v                                   v                              v
+---------------------------+  +---------------------+  +--------------------------------+
| Git Worktree + tmux 기반  |  | 사전 준비            |  | 01. cs 명령어로 실행           |
| 병렬 작업 관리 도구       |  | - tmux 설치          |  | 02. N키: 새 세션(워크트리) 생성 |
|                           |  | - GitHub CLI 설치    |  | 03. Enter: 세션 진입           |
| 핵심 가치:                |  |                     |  | 04. Ctrl+Q: 세션 나가기        |
| - 워크트리 자동 생성/관리 |  | 설치 방법 (택 1)     |  | 05. N키: 추가 세션 생성        |
| - 여러 에이전트 동시 실행  |  | - brew install       |  | 06. Tab: Diff 탭 확인          |
| - 한 번에 GitHub 푸시     |  | - curl 스크립트      |  | 07. P키: 커밋 + 푸시           |
+---------------------------+  +---------------------+  +--------------------------------+

선수 지식 체크리스트

• [ ] Git 기본 개념 (브랜치, 커밋, 푸시)
• [ ] Git Worktree 개념 (하나의 저장소에서 여러 작업 디렉터리 생성)
• [ ] 터미널 기본 사용법 (CLI 명령어)
• [ ] 클로드 코드 기본 사용법 (23장 Claudia 또는 클로드 코드 기초)

핵심 키워드

24-1 Claude Squad란?

한 줄 요약

Claude Squad는 Git Worktree와 tmux를 결합하여 여러 클로드 코드 에이전트를 동시에 실행하고 관리할 수 있게 해주는 오픈소스 터미널 앱이다.

쉬운 설명 — 비유로 이해하기

일반적인 워크트리 사용 (수동):
  1. git worktree add 명령으로 워크트리 생성 (귀찮음)
  2. cd로 이동해서 클로드 코드 실행 (귀찮음)
  3. 작업 끝나면 워크트리 정리 (귀찮음)
  -> 이걸 작업마다 반복!

Claude Squad 사용 (자동):
  1. cs 실행 -> N 키 -> 이름만 입력
  -> 워크트리 생성, 클로드 코드 실행, 정리까지 자동!
  -> 여러 작업을 동시에 진행 + 한 번에 GitHub 푸시!

비유:
  수동 = 요리사가 재료 준비, 조리, 설거지를 매번 직접
  Claude Squad = 주방 매니저가 여러 요리사에게 일 분배하고 관리

실무 예제 — 왜 필요한가?

시나리오: 프론트엔드 UI 개선 + 데이터베이스 마이그레이션을 동시에 진행

❌ 워크트리 없이:
  - 하나의 브랜치에서 작업 -> 서로 충돌 위험
  - 하나 끝나야 다음 작업 시작 (시간 낭비)

❌ 워크트리만 사용:
  - git worktree add ../improve-ui
  - cd ../improve-ui && claude
  - 또 다른 터미널에서 git worktree add ../migrate-db
  - cd ../migrate-db && claude
  -> 관리가 복잡하고 귀찮음

✅ Claude Squad 사용:
  - cs 실행 -> N 눌러 'improve-ui' 생성 -> N 눌러 'migrate-db' 생성
  - 각 세션에서 클로드 코드가 독립적으로 작업
  - J/K 키로 세션 간 전환, Tab으로 Diff 확인
  - P 키로 한 번에 푸시

핵심 체크포인트

• [ ] Claude Squad는 GUI가 아닌 터미널(tmux) 기반 도구이다
• [ ] 각 인스턴스는 독립된 워크트리에서 실행되므로 메인 브랜치에 영향을 주지 않는다
• [ ] 현재 macOS에서만 사용 가능하다
• [ ] 오픈소스 프로젝트이며 github.com/smtg-ai/claude-squad에서 관리된다

24-2 Claude Squad 설치하기

한 줄 요약

tmux와 GitHub CLI를 사전 설치한 후, Homebrew 또는 curl 스크립트로 Claude Squad를 설치하고 cs 명령어로 실행을 확인한다.

쉬운 설명 — 설치 순서

[사전 준비]
  1. tmux 설치 (터미널 멀티플렉서)
     -> github.com/tmux/tmux/wiki/Installing
  2. GitHub CLI 설치 (gh 명령어)
     -> cli.github.com

[Claude Squad 설치 - 방법 1: Homebrew]
  brew install claude-squad
  ln -s "$(brew --prefix)/bin/claude-squad" "$(brew --prefix)/bin/cs"

[Claude Squad 설치 - 방법 2: curl]
  curl -fsSL https://raw.githubusercontent.com/smtg-ai/claude-squad/main/install.sh | bash

[설치 확인]
  cs 입력 -> Claude Squad 화면이 나오면 설치 완료!
  "No agents running yet. Spin up a new instance with 'n' to get started!"

실무 예제 — 설치 후 확인

$ cs

     Preview                          Diff
  +--------------------------------------------+
  |                                            |
  |  ██████ █      ████  █   █ ████  ████      |
  |  █      █     █    █ █   █ █   █ █         |
  |  █      █     █████  █   █ █   █ ████      |
  |  █      █     █    █ █   █ █   █ █         |
  |  ██████ █████ █    █ ████  ████  ████      |
  |              SQUAD                          |
  |                                            |
  |  No agents running yet.                    |
  |  Spin up a new instance with 'n'           |
  |  to get started!                           |
  +--------------------------------------------+

하단 단축키:
  n new | N new with prompt | ? help | q quit

핵심 체크포인트

• [ ] tmux와 GitHub CLI는 Claude Squad의 필수 의존성이다
• [ ] 설치 방법은 Homebrew와 curl 두 가지가 있다
• [ ] 설치 후 cs 명령어로 실행할 수 있다
• [ ] ln -s 명령은 claude-squad를 짧은 cs로 실행하기 위한 심볼릭 링크 생성이다

24-3 Claude Squad 사용법

한 줄 요약

cs 실행 후 N 키로 세션을 생성하고, Enter로 진입하여 클로드 코드를 사용하고, Ctrl+Q로 나와서 백그라운드로 실행시키며, Diff 탭과 P 키로 변경 사항을 확인하고 푸시한다.

쉬운 설명 — 7단계 워크플로

Step 01: 프로젝트 디렉터리에서 cs 실행
         -> Claude Squad 대시보드 열림

Step 02: N 키로 새 세션 생성
         -> 기능 이름 입력 (예: improve-ui)
         -> 독립 워크트리가 자동 생성됨
         -> 노란색 글자로 워크트리 경로 표시

Step 03: Enter 키로 세션 진입
         -> 클로드 코드 터미널이 풀스크린으로 열림
         -> 일반 클로드 코드와 동일하게 사용

Step 04: Ctrl+Q로 세션 나가기
         -> 대시보드로 복귀
         -> 세션은 백그라운드에서 계속 실행 중

Step 05: N 키로 추가 세션 생성
         -> 새로운 워크트리 + 인스턴스 생성
         -> J/K 키로 인스턴스 간 이동

Step 06: Tab 키로 Diff 탭 확인
         -> 각 워크트리에서 변경된 코드 확인
         -> additions(+) / deletions(-) 표시

Step 07: P 키로 푸시
         -> P 누른 후 Y 키로 확인
         -> 커밋 + GitHub 리포지터리에 푸시

실무 예제 — 키보드 단축키 정리

[대시보드 화면]
  n     새 인스턴스 생성 (기본)
  N     프롬프트와 함께 새 인스턴스 생성
  Enter 선택한 인스턴스에 진입
  J     다음(아래) 인스턴스로 이동
  K     이전(위) 인스턴스로 이동
  Tab   Preview <-> Diff 탭 전환
  D     인스턴스 삭제 (Kill)
  P     변경 사항 푸시 (Push branch)
  c     체크아웃 (Checkout)
  w/o   열기 (Open)
  ?     도움말
  q     종료

[세션 진입 후]
  Ctrl+Q  세션에서 나가기 (백그라운드 실행 유지)

핵심 체크포인트

• [ ] 세션을 생성하면 메인 브랜치와 완전 독립된 워크트리가 만들어진다
• [ ] Ctrl+Q로 나가도 세션은 백그라운드에서 계속 실행된다
• [ ] Claude Squad를 종료하지 않으면 언제든 돌아와서 확인할 수 있다
• [ ] Diff 탭에서 각 인스턴스의 코드 변경 사항을 한눈에 확인할 수 있다
• [ ] P 키 -> Y 키로 변경 사항을 즉시 커밋하고 GitHub에 푸시할 수 있다
• [ ] 머지하기 전까지는 메인 브랜치에 영향을 주지 않는다

연습문제

문제 1: Claude Squad의 핵심 구성 요소

Claude Squad가 내부적으로 사용하는 두 가지 핵심 기술은 무엇이며, 각각의 역할은?

문제 2: 워크플로 실습

다음 시나리오를 Claude Squad로 처리하는 순서를 작성하세요: "프로젝트에서 로그인 기능 개선과 대시보드 리디자인을 동시에 진행하고 싶다."

문제 3: Claude Squad vs 수동 워크트리

Claude Squad 없이 Git Worktree만으로 같은 작업을 수행할 때의 단점 3가지를 설명하세요.

부록 A — 용어 사전

부록 B — 비교표

Claude Squad vs 수동 워크트리 관리

Claude Squad 키보드 단축키 전체 정리

부록 C — 참고 자료